home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / utilities / text / man379.lha / doc / doc2man.doc next >
Encoding:
Text File  |  1995-02-04  |  2.7 KB  |  85 lines
  1.  
  2. ; doc2man
  3. ; Fri Feb 03 23:50:02 1995
  4.  
  5. doc2man(8) - maint utils
  6.  
  7. NAME:
  8.  
  9. doc2man - convert ascii doc file (formatted) to man page format (37.9, Feb/95)
  10.  
  11. SYNOPSIS:
  12.  
  13. doc2man <infile >outfile
  14.  
  15. (uses stdio so i/o redirection will be desired)
  16.  
  17. DESCRIPTION:
  18.  
  19. {doc2man} will convert a specially-formatted text file into a manual page
  20. file, formattable by the {man} program.  See one of the sample mandocs for
  21. a good example of the file format.
  22.  
  23. First line must be of the form:
  24.  
  25.     filename(n) - optional text here
  26.  
  27. where _filename_ is the output name of the man page, and _n_ is a section number
  28. corresponding with the following (modeled after the Unix convention):
  29.  
  30.     1 = User Commands
  31.     2 = System Kernel Functions
  32.     3 = C Library Functions
  33.     4 = Device Interfaces
  34.     5 = File Formats
  35.     6 = Games and Demos
  36.     7 = Environments and Tables
  37.     8 = Maintenance Commands
  38.  
  39. Following that and a blank line will come the rest of the file, broken into
  40. subsections.  Each subsection will start with its own header, isolated on
  41. a line all in uppercase characters and terminated with a colon.
  42.  
  43. doc2man will recognize some particularly common section types, whose names will
  44. be represented in the man file with an encoded identifier to save space.  Any
  45. unrecognized ones will have their text represented verbatim.  Recognized are:
  46. NAME, SYNOPSIS, DESCRIPTION, EXAMPLE, PORTABILITY, SEE ALSO, FILES,
  47. BUGS, NOTES, OPTIONS, RETURNS, AUTHOR, LICENCE
  48.  
  49. Note that often variations will also be recognized, e.g. plurals and such.
  50. When {man} formats the output, the subsection headers will be displayed flush
  51. left and in bold type.
  52.  
  53. The body of the section, which follows, will be displayed justified.  However,
  54. paragraphs may be broken as frequently as desired for visual clarity in the
  55. ascii file -- doc2man will automatically strip the linefeeds.  Multiple
  56. paragraphs should be separated by a blank line -- this will be recognized and
  57. formatting will be done accordingly.  There is no limit to the number of
  58. paragraphs per subsection; sections are assumed to end when a line meeting
  59. the criteria for a header above is encountered.
  60.  
  61. Special formatting codes may be embedded within the file for character type
  62. variety.  Following are a line of set type, and its formatted counterpart:
  63.  
  64.     _To get_:    Plain, {italicized}, |bolded|, _underlined_
  65.  
  66.     _Type_:    Plain, \{italicized\}, \|bolded\|, \_underlined\_
  67.  
  68. Note, however, that to use one of the above formatting characters literally
  69. it must be escaped with a backslash (as must a backslash itself):
  70.  
  71.     _To get_:    You will notice the \_symbols\\ \|\|\| in this text\}.
  72.  
  73.     _Type_:    You will notice the \\\_symbols\\\\ \\\|\\\|\\\| in this text\\\}.
  74.  
  75. The file may simply end after the last section's text.
  76.  
  77. OPTIONS:
  78.  
  79. None at present.
  80.  
  81. SEE ALSO:
  82.  
  83. {man2doc}, {guide2man}, {man}
  84.  
  85.